home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Docs / Includes / UFileBasedDocument.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  18.5 KB  |  478 lines  |  [TEXT/MPS ]
  1. // UFileBasedDocument.h
  2. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  3.  
  4. #ifndef __UFILEBASEDDOCUMENT__
  5. #define __UFILEBASEDDOCUMENT__
  6.  
  7. // MacApp
  8.  
  9. #ifndef __GEOMETRY__
  10. #include "Geometry.h"
  11. #endif
  12.  
  13. #ifndef __UDOCUMENT__
  14. #include "UDocument.h"
  15. #endif
  16.  
  17.  
  18. //----------------------------------------------------------------------------------------
  19. //  Constants for the finder CString resources
  20. //----------------------------------------------------------------------------------------
  21.  
  22. const ResType    kFinderStringType = 'STR ';
  23. const ResNumber kFinderApplicationNameID = -16396;
  24. const ResNumber kFinderMessageID = -16397;
  25.  
  26. //----------------------------------------------------------------------------------------
  27. //  Constants for the script resource
  28. //----------------------------------------------------------------------------------------
  29.  
  30. const ResType     kScriptInfoRsrcType = 'scpt';
  31. const ResNumber     kScriptInfoRsrcID = 128;
  32.  
  33. //----------------------------------------------------------------------------------------
  34. //  Constants for the selection resource
  35. //----------------------------------------------------------------------------------------
  36.  
  37. const ResNumber    kSelectionRsrcID = 1;                // rsrc id for selection rsrc
  38.  
  39. //----------------------------------------------------------------------------------------
  40. //  How to save a document.
  41. //  
  42. //  svtAlways:    Always save with SaveViaTemp. Never overwrite the existing file.
  43. //  svtAskUser:    Try to SaveViaTemp.If not possible then ask before SaveInPlace.
  44. //  sipAlways:    Always save with SaveInPlace. Never create a temporary file.
  45. //  sipAskUser: Always save with SaveInPlace, but only if user confirms.
  46. //----------------------------------------------------------------------------------------
  47.  
  48. enum SaveChoice { svtAlways, svtAskUser, sipAlways, sipAskUser };
  49.  
  50. //----------------------------------------------------------------------------------------
  51. // Forward and external class declarations. 
  52. //----------------------------------------------------------------------------------------
  53.  
  54. struct StandardFileReply;
  55. class TFile;
  56. class TSaveFileDocCommand;
  57. class TCloseFileDocCommand;
  58. #if qContainer
  59. class TODPartView;
  60. #endif
  61.  
  62. //----------------------------------------------------------------------------------------
  63. // TFileBasedDocument: Corresponds to a Finder document. Managed document data in files
  64. // and main memory.
  65. //----------------------------------------------------------------------------------------
  66.  
  67. class TFileBasedDocument : public TDocument
  68. {
  69.     MA_DECLARE_CLASS;
  70.     
  71. public:
  72.     TFile*            fFile;                            // volume/directory/filename
  73.  
  74.     Boolean            fFileExists;                    // whether a disk file representing this
  75.                                                     // model exists
  76.  
  77.     SaveChoice        fHowToSave;                        // how to save files
  78.  
  79.     OSType            fScrapType;                        // document's private scrap type
  80.  
  81.     TFileBasedDocument();
  82.         // Constructor
  83.         
  84.     void IFileBasedDocument(TFile* itsFile, OSType itsScrapType);
  85.         // Initialization method for TFileBasedDocument.
  86.  
  87.     virtual void DoInitialState();
  88.     
  89.     virtual TFile* DoMakeFile(CommandNumber itsCommandNumber);
  90.         // Default behavior is to gApplication->DoMakeFile.  May be overridden to create
  91.         // a file of your own special type.
  92.  
  93.     //    virtual TFileHandler* DoMakeFileHandler(TFile* itsFile);
  94.     //        // Creates and returns a TFileHandler for this object.
  95.  
  96.     virtual ~TFileBasedDocument();
  97.         // This does not call FreeData by default, since you may need to control the order
  98.         // in which things are freed. Your override of TDocument::Free can call FreeData if
  99.         // convenient.
  100.  
  101.     virtual void RegainControl();
  102.         // Called just after the application has been resumed to allow the
  103.         // document to change its title according to an outside file name change.
  104.  
  105.  
  106.     //------------------------------------------------------------------------------------
  107.     // Opening Documents
  108.     //------------------------------------------------------------------------------------
  109.  
  110.     virtual void AboutToSaveFile(TFile* theSaveFile,
  111.                                  CommandNumber itsCmd,
  112.                                  Boolean& makingCopy);
  113.         // Called from file handler right after the SFPutFile (if any) and before deciding
  114.         // between SaveViaTemp & SaveInPlave. Applications can use the name in an alert
  115.         // and/or modify the makingCopy parameter if they do not want to have the document
  116.         // renamed.
  117.  
  118.     virtual Boolean FindDocument(TFile* aFile);
  119.         // True if this file is already open
  120.  
  121.     virtual void DoNeedDiskSpace(TFile* itsFile,
  122.                                  long& dataForkBytes,
  123.                                  long& rsrcForkBytes);
  124.         // Bytes required to store SAVE file(s) on disk. When called, both parameters are
  125.         // set to 0 for you.
  126.  
  127.     virtual void DoRead(TFile* aFile, Boolean forPrinting);
  128.         // The default behavior is to just read the printinfo from the document's
  129.         // data-fork by calling DoReadPrintInfo (useful huh?)
  130.  
  131.     virtual void DoReadPrintInfo(TFile* aFile, Boolean forPrinting);
  132.         // The default behavior is to just read the printinfo from the document's
  133.         // data-fork (useful huh?)
  134.  
  135. #if qAttachable
  136.     virtual void DoReadScript(TFile* aFile, Boolean forPrinting);
  137.         // The default behavior is to just read the script from the resource fork.
  138. #endif
  139.  
  140.     virtual void DoReadSelection(TFile* aFile, Boolean forPrinting);
  141.         // The default behavior is to just read the selection from the resource fork.
  142.  
  143.     virtual void DoWrite(TFile* aFile, Boolean makingCopy);
  144.         // makingCopy indicates whether this save is for making a copy of the document
  145.         // (vs. a regular Save or Save As); disk-based documents (especially) might
  146.         // optimize their behaviour if this is true.
  147.         
  148.     virtual void DoWriteFinderString(TFile* aFile, Boolean makingCopy);
  149.         // The default behavior is to retrieve the finder message and application name
  150.         // and write the appropriate CString to the document's resource-fork.
  151.         
  152.     virtual void DoWritePrintInfo(TFile* aFile, Boolean makingCopy);
  153.         // makingCopy indicates whether this save is for making a copy of the document
  154.         // (vs. a regular Save or Save As); disk-based documents (especially) might
  155.         // optimize their behaviour if this is true. The default behavior is to just write
  156.         // the printinfo to the document's resource-fork (useful huh?)
  157.  
  158. #if qAttachable
  159.     virtual void DoWriteScript(TFile* aFile, Boolean makingCopy);
  160.         // makingCopy indicates whether this save is for making a copy of the document
  161.         // (vs. a regular Save or Save As); disk-based documents (especially) might
  162.         // optimize their behaviour if this is true. The default behavior is to just write
  163.         // the script to the document's resource-fork (useful huh?)
  164. #endif
  165.  
  166.     virtual void DoWriteSelection(TFile* aFile, Boolean makingCopy);
  167.         // makingCopy indicates whether this save is for making a copy of the document
  168.         // (vs. a regular Save or Save As); disk-based documents (especially) might
  169.         // optimize their behaviour if this is true. The default behavior is to just write
  170.         // the selection to the document's resource-fork
  171.  
  172.     virtual void ReadDocument(Boolean forPrinting);
  173.         // Called to read an existing document for display or printing.
  174.  
  175.     virtual void ReadStationery(TFile* itsNewFile);
  176.         // Called to read an existing stationery pad for display.
  177.  
  178.     //------------------------------------------------------------------------------------
  179.     // Saving Documents
  180.     //------------------------------------------------------------------------------------
  181.  
  182.     virtual void GetSaveLocation(CommandNumber itsCommandNumber, CAEDesc& theSaveDesc);
  183.         // Creates an CAEDesc describing where the document would be saved
  184.  
  185.     virtual void DoSave(CommandNumber itsCommandNumber);
  186.         // Handle the cSave, cSaveAs, and cSaveCopy commands
  187.  
  188.     virtual void SaveDocument(CommandNumber itsCommandNumber);
  189.         // Try to save the document to disk
  190.  
  191.     virtual void FileHasBeenSaved(const CStr255& newName);
  192.         // Called when a save successfully completes and we are switching to the new file
  193.         // (ie., not a Save a Copy In).
  194.  
  195.     virtual void SFPutParms(CommandNumber itsCommandNumber,
  196.                             CStr255& prompt,
  197.                             CStr255& defaultName,
  198.                             ResNumber& dlgID,
  199.                             CPoint& where,
  200.                             ProcPtr& dlgHook,
  201.                             ProcPtr& modalFilter,
  202.                             Ptr& activeList,
  203.                             ProcPtr& activateProc,
  204.                             StandardFileReply* reply,
  205.                             void*& yourDataPtr);
  206.         // Called to return all the parameters that should be passed to CustomPutFile or
  207.         // SFPutFile. Defaults to prompt gotten from resource file; defaultName not
  208.         // changed;
  209.         //        dlgID = sfPutDialogID or putDlgID;
  210.         //        where = (-1, -1) or (100, 100);
  211.         //        dlgHook = NULL;
  212.         //        modalFilter = gMacAppStandardFileFilter;
  213.         //        activeList = NULL;
  214.         //        activateProc = NULL;
  215.         //        yourDataPtr = NULL.
  216.  
  217.  
  218.     //------------------------------------------------------------------------------------
  219.     // Closing Documents
  220.     //------------------------------------------------------------------------------------
  221.  
  222.     virtual TCloseDocCommand* MakeCloseCommand();
  223.         // This method creates a document saving command appropriate to this type
  224.         // of document.
  225.  
  226.     //------------------------------------------------------------------------------------
  227.     // Revert
  228.     //------------------------------------------------------------------------------------
  229.  
  230.     virtual void RevertDocument();
  231.         // If fSaveExists is true then reverts to the file saved on disk, otherwise merely
  232.         // resets the print handler and calls doInitialState. Calls FreeData to free any
  233.         // existing data and commits any currently active command.
  234.  
  235.  
  236.     //------------------------------------------------------------------------------------
  237.     // Miscellaneous
  238.     //------------------------------------------------------------------------------------
  239.  
  240.     virtual void CheckFile(ResNumber rsrcId, short rsrcIndex, Boolean reverting);
  241.         // Check to see if the disk file has changed. If so put up alert phFileChanged
  242.         // after setting ^0 to fTitle and ^1 to the CString specified by the rsrcId and
  243.         // rsrcIndex. If user cancels, signal Failure(noErr, messageCancelled). If reverting
  244.         // is true, then I/ O errors and nonmatching file types will cause a Failure.
  245.         // Otherwise, this is a Save and any I/ O errors and nonmatching file type will be
  246.         // ignored.
  247.  
  248.     virtual void Close();
  249.         // Close a document.  Closes the associated file.  ??? NOTE: Must never be called
  250.         // for a document related to a view in the Clipboard.
  251.  
  252.     virtual void CloseFile();
  253.         // Called to free in memory data associated with the currently opened document.
  254.         // The default is to call fFile->Close(true) to force the file close.
  255.  
  256.     //    virtual TFileHandler* GetFileHandler();
  257.     //        // accessor for fFileHandler
  258.  
  259.     virtual Boolean IsChanged();
  260.         // If the document has been changed
  261.  
  262.     virtual void SetTitle(const CStr255& aTitle);
  263.         // Does fFile->SetName to aTitle and calls SetTitleForDoc for each window of the
  264.         // document.
  265.  
  266.     virtual void GetFinderMessage(CStr255& theMessage);
  267.         // Override this method to provide a message for use by the finder if your
  268.         // document is not be opened directly by the user.  The default behavior is to set
  269.         // theMessage to an empty CString.
  270.  
  271.     virtual void DoClose(CommandNumber aCommand,
  272.                          Boolean useAppleEvent = TRUE);
  273.         // This method creates a document closing command appropriate to this type
  274.         // of document and then posts it.  Pass a FALSE if this close is NOT
  275.         // supposed to generate an AppleEvent.
  276.  
  277.     //------------------------------------------------------------------------------------
  278.     // File Handling
  279.     //------------------------------------------------------------------------------------
  280.  
  281.     virtual Boolean FileAlreadyOpen(TFile* aFile);
  282.         // True if the file for the model is already open
  283.  
  284.     virtual OSErr FileChanged(Boolean checkType);
  285.         // Returns noErr if fSaveExists is false or if the file's modification date
  286.         // matches fModDate. If checkType is true then returns errFTypeChanged if the file
  287.         // type has changed. If the file exists but with a different modification date,
  288.         // returns errFileChanged.
  289.  
  290.     virtual Boolean FileExists();
  291.         // Default returns the status of fFileExists
  292.  
  293.     virtual TFile* GetFile();
  294.         // Return the file for this document. 
  295.  
  296.     virtual void SetFile(TFile* itsNewFile);
  297.         // Set the file for this document, disposing of the old file if it exists
  298.  
  299.     virtual void GetFileName(CStr63& aName);
  300.         // Return the name of the file
  301.  
  302.     virtual Boolean GetSaveInfo(CommandNumber itsCommandNumber,
  303.                                 Boolean copyFInfo,
  304.                                 CInfoPBRec& cInfo);
  305.         // Called to get the desired file info for saving the file. Default copies the
  306.         // info from the current file if fSaveExists AND copyFInfo, otherwise it just sets
  307.         // the file type and creator based on the fields of this. If an error occurs
  308.         // calling the file system, the cInfo record will not be filled in. Returns true
  309.         // if it successfully gets the info from the file.
  310.  
  311.     virtual void GetTempName(CStr63& fileName);
  312.         // Return a temporary name for saving the file. The filename is constructed in two
  313.         // parts: the first part is the document's name, or the application's name if the
  314.         // document is untitled. The second part, appended to the first part, is a pseudo-
  315.         // random number based on the tick count and number of seconds since boot.
  316.  
  317.     virtual void ReadFile(Boolean forPrinting);
  318.         // Called to read an existing file for display or printing.
  319.  
  320.     virtual void RequestFileName(CommandNumber itsCommandNumber,
  321.                                  Boolean makingCopy,
  322.                                  TFile* aFile);
  323.         // Asks the user for a filename for the document. Calls SFPutParms
  324.         // and then SFPPutFile. Fails if the user clicks the Cancel button to end the put
  325.         // file dialog.
  326.  
  327.     virtual void SaveFile(CommandNumber itsCommandNumber,
  328.                           Boolean askForFilename,
  329.                           Boolean copyFInfo,
  330.                           Boolean makingCopy);
  331.         // Try to save the document to disk; If askForFilename, put up a Std File box; If
  332.         // makingCopy, then this is for the Save a Copy In command, so we do not rename
  333.         // the document. This method calls FlushVol (which takes care of the requirements
  334.         // of SaveInPlace, and SaveViaTemp.
  335.  
  336.     virtual void SaveInPlace(CommandNumber itsCommandNumber,
  337.                              Boolean makingCopy,
  338.                              Boolean copyFInfo,
  339.                              TFile* itsFile);
  340.         // Called to save a document in place. Default is to delete the existing file if
  341.         // NOT (fDataOpen OR fRsrcOpen). If you have disk based document, you have to
  342.         // decide whether to allow saving in place. makingCopy is true if this save is
  343.         // making a copy of the document (vs. a regular Save or Save As) copyFInfo is true
  344.         // if the file information should be copied to the new file Caller is responsible
  345.         // for calling FlushVol after this.
  346.  
  347.     virtual void SaveViaTemp(CommandNumber itsCommandNumber,
  348.                              Boolean makingCopy,
  349.                              Boolean copyFInfo,
  350.                              TFile* itsFile);
  351.         // Called to save the document by creating a temporary copy of the file and
  352.         // renaming it. MacApp uses this method except when there is not enough disk space
  353.         // available. makingCopy is true if this save is making a copy of the document
  354.         // (vs. a regular Save or Save As) copyFInfo is true if the file information
  355.         // should be copied to the new file Caller is responsible for calling FlushVol
  356.         // after this.
  357.  
  358.     virtual void SetFileName(const CStr63& aName);
  359.         // Default behavior calls fFile->SetName with aName
  360.  
  361.     virtual Boolean ValidateFileSpec();
  362.         // Determine if the file's name has changed and update the document's if so.
  363.  
  364.     //------------------------------------------------------------------------------------
  365.     // Scripting Support
  366.     //------------------------------------------------------------------------------------
  367.  
  368.     virtual long CountContainedObjects(DescType desiredType);
  369.  
  370.     virtual void DoAESave(TAppleEvent* message,
  371.                           TAppleEvent* reply);
  372.  
  373.     virtual void DoAEClose(TAppleEvent* message,
  374.                            TAppleEvent* reply);
  375.  
  376.     virtual MScriptableObject* GetContainedObject(DescType desiredType,
  377.                                                   DescType selectionForm,
  378.                                                   const CAEDesc& selectionData);
  379.  
  380. #if qContainer
  381.     //------------------------------------------------------------------------------------
  382.     // Container Application Support
  383.     //------------------------------------------------------------------------------------
  384.  
  385. public:
  386.     virtual CADocumentRef GetContainer();
  387.         // Overridden to return the container document reference. 
  388.         
  389.     void RegisterCAHandlers();
  390.         // Register the callbacks for this newly read document.
  391.     
  392.     virtual void AddODPartView(TODPartView* thePartView);
  393.         //add a view pointer to the list of ODPartViews
  394.         
  395.     virtual void DeleteODPartView(TODPartView* thePartView);
  396.         //remove a view pointer from the list of ODPartViews
  397.         
  398.     TList*    fODPartViewList;
  399.         //list of ODPartViews
  400. private:
  401.     static void MakeDatedUniqueFSSpec(FSSpec* fsSpec);
  402.  
  403. protected:
  404.     CADocumentRef    fContainerDocument;
  405.     CAOffset        fContainerOffset;
  406.     CASize            fContainerLength;
  407.     WindowPtr        fRootWindowRef;
  408.  
  409. #endif // qContainer
  410.     
  411. };
  412.  
  413. //----------------------------------------------------------------------------------------
  414. // TSaveFileDocCommand: Closes a file-based document.
  415. //----------------------------------------------------------------------------------------
  416.  
  417. class TSaveFileDocCommand : public TSaveDocCommand
  418. {
  419.     MA_DECLARE_CLASS;
  420.     
  421. public:
  422.     TSaveFileDocCommand();
  423.     virtual ~TSaveFileDocCommand();
  424.         
  425.     
  426.         // Perform final command preparation.
  427.         
  428.     void ISaveFileDocCommand(CommandNumber itsCommandNumber,
  429.                              TDocument* itsDocument);
  430.     void ISaveFileDocCommand(TDocument* itsDocument,
  431.                              TAppleEvent* message,
  432.                              TAppleEvent* reply);
  433.         // Initialize the TSaveFileDocCommand procedurally. 
  434.  
  435.     virtual void DoIt();
  436.         // Actually perform the document closing. 
  437.         
  438.     virtual TAppleEvent* MakeAppleEvent();
  439.  
  440. protected:
  441.     TFile*        fSaveFile;
  442. };
  443.  
  444. //----------------------------------------------------------------------------------------
  445. // TCloseFileDocCommand: Closes a file-based document.
  446. //----------------------------------------------------------------------------------------
  447.  
  448. class TCloseFileDocCommand : public TCloseDocCommand
  449. {
  450.     MA_DECLARE_CLASS;
  451.     
  452. public:
  453.     TCloseFileDocCommand();
  454.     virtual ~TCloseFileDocCommand();
  455.         
  456.     
  457.         // Perform final command preparation.
  458.         
  459.     void ICloseFileDocCommand(CommandNumber itsCommandNumber,
  460.                               TDocument* itsDocument);
  461.     void ICloseFileDocCommand(TDocument* itsDocument,
  462.                               TAppleEvent* message,
  463.                               TAppleEvent* reply);
  464.         // Initialize the TCloseFileDocCommand procedurally. 
  465.  
  466.     virtual TAppleEvent* MakeAppleEvent();
  467.         // Make an Apple Event equivalent to the command.
  468.  
  469.     virtual void DoIt();
  470.         // Actually perform the document closing. 
  471.         
  472. protected:
  473.     TFile*                fCloseFile;
  474.     CommandNumber         fSaveCommand;
  475. };
  476.  
  477. #endif // __UFILEBASEDDOCUMENT__
  478.